AsciiDocの文書をCodePipeline/CodeBuildでHTMLに変換してみた

かたいなか

2018.07.30

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

こんにちは、かたいなかです。

今回はGitHubにpushしたAsciiDocの文書をCodePipeline/CodeBuildでをHTMLに自動で変換する方法をご紹介します。

AsciiDocとは

AsciiDocはドキュメントや記事、スライドショーなどを記述するためのテキストドキュメントのフォーマットです。AsciiDocのファイルはHTMLやPDF、EPUBなど様々な形式へ変換することができます。

Markdownよりも表現力が高いのも特徴で快適にドキュメントを作成することができます。

また、AsciiDocではPlantUMLなどを文書内に埋め込むことができ、UMLを多用した視覚的にわかりやすいドキュメントを容易に作成できます。

なぜHTMLに変換するのか

GitHub上ではそのままでもAsciiDocの形式のファイルをある程度きちんと表示してくれます。しかし、PlantUMLで記述した部分については図に変換されることなく文字列のまま表示されてしまいます。

また、開発者以外の方に見てもらう場合、GitHub上のドキュメントを参照してもらうのは難しい場合があります。

そのため、今回はこの部分も含めてHTMLに変換しS3上に出力し、リンクからドキュメントを閲覧できるようにします。

今回の構成

今回は下の図のような構成を組んでいきます。

構成図

今回はGitHubでmasterブランチに変更があったときに、CodePipelineに通知してもらい、CodeBuildでHTMLへの変換とS3へのアップロードを行うようにします。

実際にやってみる

変換するAsciiDocのファイル

まずは、今回変換するファイルを用意し、プロジェクトのルートに adoc という拡張子をつけて保存しましょう。

この記事内の例では以下のような内容のファイルを使用します。

= PlantUMLを含んだAsciiDocをCodeBuild/CodePipelineでHTMLに変換するテスト

https://s3-ap-northeast-1.amazonaws.com/asciidoc-codepipeline-example/README.html[変換後]

== GitHub上で表示される

* このあたりは
* GitHubで普通に表示される

== Github上では表示できない
* PlantUmlはGitHub上では表示されない(ただの文字列になる)

[plantuml, diagram-classes, png]
----
class Animal {
  run()
}

class Cat extends Animal {
}
----

CodeBuildでの定義するビルド定義ファイル

次に、CodeBuildでどのようなコマンドを実行するかを定義するbuildspec.ymlというファイルをプロジェクトルートに準備します。

version: 0.2

phases:
  build:
    commands:
      - echo Generating html...
      - find . -name "*.adoc" -type f | xargs asciidoctor -r asciidoctor-diagram -D output 
  post_build:
    commands:
      - (if [[ "$CODEBUILD_BUILD_SUCCEEDING" == "0" ]]; then exit 1; else exit 0; fi) ## ビルドフェーズで失敗したらアップロードを実行しない
      - echo Uploading to S3...
      - aws s3 sync output s3://$DESTINATION_BUCKET/

AsciidoctorでAsciiDocのファイルをHTMLに変換しています。変換が終わったら、aws s3 syncというコマンドでS3にアップロードしています。